0장. 실습 환경 설정

출처 — 브라이스 유·조경아·박수진·김재웅, 『RAG 마스터: 랭체인으로 완성하는 LLM 서비스』(프리렉, 2025), 0장 (pp. 15~26). 원문 PDF rag_master_final_v11_260910.pdf (2026-09-10 판)

이 장은 코드를 배우기 전에 필요한 모든 준비 — 구글 코랩 환경, 실습 코드, 오픈AI API 키 — 를 갖추는 장이다. 1장부터는 이 장에서 만든 환경이 이미 되어 있다는 전제로 진행된다.

학습 목표

이 장을 끝내면 다음을 할 수 있다. - 구글 코랩 환경을 준비하고 구글 드라이브를 마운트한다. - 책의 실습 코드 저장소를 내려받아 구글 드라이브에 올리고 코랩에서 연다. - 오픈AI 계정에 결제 수단을 등록하고 크레딧·월간 한도를 설정해 API 키를 발급받는다. - API 키를 코드에 적용하는 네 가지 방법을 구분하고, 상황에 맞는 방법을 선택한다.

전체 흐름도

[구글 계정 준비]
      │
      ▼
[구글 코랩 접속 → 새 노트 생성]
      │
      ▼
[구글 드라이브 마운트]  (drive.mount)
      │
      ▼
[실습 코드 GitHub ZIP 다운로드] ──▶ [구글 드라이브 업로드] ──▶ [Colab 으로 열기]
      │
      ▼
[오픈AI 계정 가입/로그인]
      │
      ▼
[결제 수단 등록 → 크레딧 충전 → 월간 사용 한도 설정]
      │
      ▼
[API 키 발급]  (Create new secret key — 발급 즉시 복사)
      │
      ▼
[API 키를 코드에 안전하게 적용]
      ├─ ① 터미널 환경 변수 (export / set)
      ├─ ② 코드 내 직접 입력 (비권장)
      ├─ ③ 구글 코랩 비밀 관리 (userdata.get)
      └─ ④ .env 파일 + python-dotenv  ← 이 책이 채택한 방식
      │
      ▼
[1장부터 실습 시작]

0. 용어 사전

참고 — 위쪽 4개는 이 장을 읽기 전에 알아야 하는 선행 용어다. 이 책의 첫 장이라 앞선 장이 없으므로, 원문 밖 일반 프로그래밍 지식에서 가져온다.

1. 실습 자료와 개발 환경 개요

이 책은 실습 위주로 구성되어 있고, 모든 실습 코드는 깃허브 저장소 langchain-kr/langchain-tutorial에 챕터별로 공개되어 있다. 저장소는 1장부터 9장까지 각 장의 실습 폴더(Ch01~Ch09)로 구성되어 있으며, 예제 파일을 내려받아 그대로 실행하며 따라갈 수 있다.

대부분의 실습은 구글 코랩에서 진행한다. 구글 코랩은 파이썬·주요 라이브러리가 이미 설치된 클라우드 기반 노트북 환경이라, 로컬 컴퓨터에 별도로 파이썬을 설치하거나 가상환경을 구성하지 않아도 브라우저만 있으면 바로 코드를 작성하고 실행할 수 있다. 이 장에서 다루는 준비 과정은 ① 구글 코랩 환경 준비 → ② 실습 코드 내려받기 → ③ 오픈AI API 키 발급 → ④ API 키를 코드에 안전하게 적용하기의 네 단계로 이어진다.

2. 구글 코랩 환경 준비하기

구글 코랩을 쓰려면 먼저 구글 계정이 있어야 한다. 계정이 없다면 구글 웹사이트에서 [로그인] → [계정 만들기] → [개인용]을 선택해 새로 만든다.

계정이 준비되면 구글 코랩 웹사이트에 접속해 로그인한 뒤, [Google Drive] → [새 노트]를 눌러 노트북을 생성한다. 생성된 노트의 이름(기본값 UntitledO.ipynb)은 클릭해서 바꿀 수 있다. 코드 셀을 실행하는 방법은 두 가지다 — 셀 왼쪽의 실행 버튼(▷)을 클릭하거나, 단축키 Shift + Enter를 누른다.

구글 드라이브 안의 파일(CSV·PDF 등)에 접근하려면 노트북에 드라이브를 마운트해야 한다. 다음 코드를 실행하면 팝업창이 뜬다.

from google.colab import drive
drive.mount('/content/drive')

팝업에서 [Google Drive에 연결]을 클릭하고, 사용할 구글 계정을 선택한 뒤 [Continue]를 누른다. 이어서 나타나는 접근 권한 화면에서 [Select all] 옆 체크박스를 선택하고 [Continue]를 클릭한다. Mounted at /content/drive 메시지가 출력되면 마운트가 완료된 것이며, 이후 코드에서 /content/drive/MyDrive/... 형식의 경로로 드라이브 안 파일을 그대로 읽고 쓸 수 있다. 예를 들어 CSV 파일은 다음처럼 불러온다.

import pandas as pd
pd.read_csv("/content/drive/MyDrive/Colab Notebooks/서울시_부동산_실거래가_정보.csv")

참고 — 접근 권한 팝업에서 일부 항목만 선택하고 넘어가면, 이후 코드가 필요로 하는 파일에 접근하지 못해 원인 모를 오류가 날 수 있다. 처음 마운트할 때는 [Select all]로 전체 권한을 부여하는 편이 안전하다.

3. 실습 코드 내려받기와 구글 드라이브 업로드

langchain-kr/langchain-tutorial 저장소 페이지에서 [Code] 버튼을 클릭하고 [Download ZIP]을 선택하면 실습 코드 전체를 ZIP 파일 하나로 내려받을 수 있다. (같은 화면에 HTTPS·SSH·GitHub CLI로 clone 하거나 GitHub Desktop으로 여는 방법도 함께 제공되지만, 이 장은 코랩에서 바로 쓰기 좋은 ZIP 다운로드를 기준으로 설명한다.)

다운로드한 파일은 구글 드라이브에 올려야 코랩에서 열어 볼 수 있다. 구글 드라이브에 접속해 원하는 경로(예: My Drive 아래)로 이동한 뒤, 업로드할 파일이나 압축 해제한 폴더를 그 경로로 드래그해서 놓으면 업로드가 끝난다. 업로드된 폴더 안의 노트북 파일을 마우스 오른쪽 버튼으로 클릭하고 [Open with] → [Google Colaboratory]를 선택하면 코랩에서 바로 실습 코드를 열어 실행할 수 있다. 이 책의 저자는 /content/drive/My Drive/ 아래에 langchain_tutorial 폴더로 저장해 두고, 이후 모든 실습을 이 폴더 기준으로 진행한다.

실무 체크 — §2의 구글 드라이브 마운트를 먼저 마쳐야 코랩에서 이 폴더에 접근할 수 있다. 마운트 없이 폴더를 열면 파일 경로를 찾지 못하는 오류가 난다.

4. 오픈AI API 키 발급과 과금 관리

구글 코랩 설정을 마쳤다면, 이 책이 기본으로 쓰는 오픈AI 모델을 호출하기 위한 API 키를 발급받아야 한다. 오픈AI 플랫폼(platform.openai.com)에 접속해 가입(Sign up) 또는 로그인(Log in)한다.

참고 — 원문과의 차이 — 원문은 접속 주소로 https://platform.openai.com/docs/overview를 인쇄했다. 이 경로는 현재 오픈AI 플랫폼 루트(https://platform.openai.com)로 안내되며, 로그인·API 키·청구 관리는 모두 이 루트에서 시작한다(확인 2026-09-12).

로그인한 뒤 톱니바퀴(설정) 아이콘을 눌러 청구(Billing) 메뉴로 이동해 결제 수단을 등록한다(개인 학습 목적이면 Individual을 선택). 결제 수단을 등록했다면 같은 화면에서 크레딧을 미리 충전한다 — 원문 기준 화면에서는 $5~$75 사이 금액을 입력해 충전했다(이 범위·화면 구성은 오픈AI 쪽 정책 변경에 따라 달라질 수 있다).

크레딧을 충전했다면 제한(Limits) 메뉴에서 월간 사용 한도를 반드시 설정한다.

• 월간 한도 설정(Set a monthly budget) — 이 금액을 넘으면 그 달의 나머지 API 요청이 거부된다.
• 이메일 알림 발송 한계점 설정(Set an email notification threshold) — 이 금액에 도달하면 이메일로만 알려 주고, 요청 자체를 막지는 않는다.

둘은 서로 다른 안전장치이므로, 예상치 못한 과금을 막으려면 한도를 반드시 지정하고 알림 한계점은 그보다 낮은 금액으로 함께 걸어 두는 것이 안전하다.

마지막으로 대시보드(Dashboard)의 API keys 메뉴에서 [Create new secret key]를 눌러 키를 발급받는다. 이름과 프로젝트(기본 프로젝트로 충분하다)를 지정하면 키가 생성되고, 그 자리에서 [Copy] 버튼으로 즉시 복사해 안전한 곳에 보관해야 한다.

경고 — 원문 그대로 — API 키가 유출되면 다른 사람이 그 키로 계정의 GPT 서비스를 이용할 수 있고, 그로 인한 사용 비용은 키 소유자가 부담하게 된다. 절대 키를 타인과 공유하지 말고 안전하게 보관해야 한다. 또한 발급 화면을 닫으면 그 키 값을 오픈AI 계정에서 다시 확인할 수 없으므로, 복사하지 못한 채 닫았다면 새 키를 새로 발급받아야 한다.

5. 파이썬 코드에서 API 키를 안전하게 불러오는 네 가지 방법

발급받은 API 키를 파이썬 코드에 적용하는 방법은 네 가지다. 구글 코랩에는 사용자가 직접 여는 터미널이 없어 셸 명령으로 환경 변수를 설정하기 어렵기 때문에, 코랩에서는 ②~④ 방법을 쓴다. 이 책은 그중 ④ .env 파일 방식을 기본으로 채택한다.

① 터미널에서 환경 변수 설정. 로컬 주피터 노트북처럼 터미널을 직접 여는 환경이라면 다음 명령으로 현재 세션에 환경 변수를 설정할 수 있다.

# Unix, Linux, macOS
export OPENAI_API_KEY="여러분의 API 키"
# Windows
set OPENAI_API_KEY="여러분의 API 키"

이렇게 설정하면 코드에서 os 모듈로 값을 가져올 수 있다.

import os
api_key = os.getenv('OPENAI_API_KEY')

이 방식은 터미널 세션이 끝나면 사라진다 — 새 세션을 열 때마다 다시 설정해야 하고, 영구히 남기려면 ~/.bashrc·~/.zshrc(Linux/macOS) 또는 .bash_profile(Windows Git Bash)에 같은 줄을 추가해야 한다.

② 코드 내에 직접 입력. 가장 간단하지만 가장 위험한 방법이다.

# 잘못된 예 — 키가 소스코드에 그대로 남는다
from langchain_openai import OpenAI
OpenAI(api_key="여러분의 API 키")

이 방식은 키가 소스코드 안에 그대로 노출된다. 이 코드를 깃 저장소에 올리면 키도 함께 공개 저장소에 커밋되어 유출된다 — 바로 위 §4의 경고가 실제로 벌어지는 경로다. 그래서 뒤에 나오는 ③·④ 방식처럼 키를 코드 밖에 두는 방법이 필요하다.

③ 구글 코랩 비밀 관리 기능. 코랩 좌측의 열쇠 아이콘에서 [+ 새 보안 비밀 추가]로 OPENAI_API_KEY라는 이름과 키 값을 등록해 두면, 노트북 코드에서 다음처럼 안전하게 불러올 수 있다.

# 올바른 예 — 값이 노트북 파일 자체에는 남지 않는다
from google.colab import userdata
api_key = userdata.get('OPENAI_API_KEY')

이 값은 코랩 계정에 저장되므로, 노트북을 새로 열어도 다시 등록할 필요가 없다. 다만 이 방법은 구글 코랩 환경에서만 쓸 수 있다.

④ .env 파일을 이용한 환경 변수 설정 (이 책의 방식). 환경 변수를 코드에 직접 쓰지 않고 별도 파일에 보관하는 방법이다. 먼저 코랩 왼쪽 폴더 메뉴에서 새 파일을 만들고 이름을 .env로 바꾼 뒤, 그 안에 키를 한 줄로 적는다.

# .env
OPENAI_API_KEY=여러분의 API 키

이 책은 이 파일을 /content/.env에 두었다. 다만 이 경로는 코랩 세션을 종료하고 다시 실행하면 초기화되므로, 파일을 계속 남기고 싶다면 마운트된 드라이브 위치(/content/drive/MyDrive/...)에 저장하는 편이 낫다.

.env 파일을 코드에서 읽으려면 python-dotenv 패키지가 필요하다.

!pip install python-dotenv langchain-openai

# 올바른 예 — 키가 코드가 아니라 .env 파일에만 있다
from dotenv import load_dotenv
import os
from langchain_openai import OpenAI

# .env 파일에서 환경 변수 로드(.env 파일 경로)
load_dotenv("/content/.env")
# 환경 변수에서 API 키 가져오기
api_key = os.getenv("OPENAI_API_KEY")
# 오픈AI 대규모 언어 모델 초기화
llm = OpenAI(api_key=api_key)

load_dotenv()는 지정한 경로의 .env 파일을 읽어 그 안의 값들을 환경 변수로 등록한다. 인자 없이 호출하면 현재 디렉터리에서 .env를 찾으므로, 파일이 다른 경로에 있다면 위 예처럼 load_dotenv("/path/to/.env")로 경로를 직접 지정해야 한다. 이어서 os.getenv("OPENAI_API_KEY")로 그 이름의 값을 꺼내 오고, 마지막으로 OpenAI(api_key=api_key)로 언어 모델을 초기화한다. load_dotenv()로 값을 로드하면 라이브러리가 OPENAI_API_KEY라는 이름을 자동으로 찾으므로 api_key 인자를 아예 생략할 수도 있지만, 환경 변수 이름이 다르거나 여러 키를 동시에 관리한다면 os.getenv()로 명시적으로 지정하는 편이 안전하다.

핵심 개념 정리

실무 체크리스트

• [ ] 구글 드라이브가 마운트되어 /content/drive/... 경로로 파일에 접근할 수 있는가?
• [ ] 실습 코드 저장소를 ZIP으로 내려받아 구글 드라이브에 올렸는가?
• [ ] 오픈AI 계정에 결제 수단을 등록하고 크레딧을 충전했는가?
• [ ] 월간 사용 한도(Set a monthly budget)를 설정해 예상치 못한 과금을 막았는가?
• [ ] 이메일 알림 한계점을 한도보다 낮은 금액으로 함께 설정했는가?
• [ ] API 키를 발급 직후 안전한 곳에 복사해 두었는가(창을 닫으면 다시 볼 수 없다)?
• [ ] API 키를 코드에 직접 하드코딩하지 않고 .env 또는 코랩 비밀 관리로 분리했는가?
• [ ] .env 파일이 깃 저장소에 커밋되지 않도록 조치했는가?
• [ ] load_dotenv()에 넘긴 경로가 실제 .env 파일 위치와 일치하는가?

연습문제

1. 시나리오형. 동료가 실습 코드를 실행하다가 "OPENAI_API_KEY를 찾을 수 없다"는 오류를 만났다. .env 파일은 /content/.env에 있고, 코드에서는 load_dotenv()를 인자 없이 호출했다. 무엇이 문제이고 어떻게 고쳐야 하는가?
2. 비교형. 로컬 주피터 노트북과 구글 코랩 환경에서 API 키를 안전하게 관리하는 방법이 서로 다른 이유는 무엇인가? 두 환경의 차이를 근거로 설명하라.
3. 판단형. 학습용으로 발급받은 API 키를 실수로 깃허브 공개 저장소에 커밋했다. 지금 바로 취해야 할 조치는 무엇인가?
4. 개념 확인형. 오픈AI 청구 화면의 "월간 한도 설정(Set a monthly budget)"과 "이메일 알림 발송 한계점 설정(Set an email notification threshold)"은 각각 무엇을 막고, 무엇을 막지 못하는가?

부록 A. 핵심 비교표

API 키를 코드에 넣는 방법 — 코드 내 직접 입력 vs .env 파일

API 키 저장 위치 — 터미널 환경 변수 vs 구글 코랩 비밀 관리

부록 B. 추천 참고 자료

외부 자료 (Tier 1 공식, 생존 확인 2026-09-12)

• 책 공식 실습 저장소 (GitHub, ZIP 다운로드) — langchain-kr/langchain-tutorial
• 구글 코랩 공식 시작 안내 — Colab 소개 노트북
• 구글 코랩 비밀 관리(Secrets) 공식 노트북 — Colab Secrets 안내
• python-dotenv 공식 문서 — python-dotenv 사용법

본 책 연계 챕터

부록 C. 연습문제 풀이

1. (문제 1 풀이) load_dotenv()를 인자 없이 호출하면 현재 작업 디렉터리에서 .env를 찾는다. .env가 /content/.env에 있는데 코드 실행 위치(현재 디렉터리)가 다르면 파일을 찾지 못해 환경 변수가 로드되지 않는다. load_dotenv("/content/.env")처럼 경로를 직접 지정하면 해결된다.
2. (문제 2 풀이) 로컬 주피터 노트북은 사용자가 직접 여는 터미널이 있어 export/set 명령으로 세션에 환경 변수를 설정할 수 있다. 반면 구글 코랩은 사용자가 여는 터미널이 없는 브라우저 기반 환경이라 셸 명령 자체를 쓸 수 없고, 대신 코랩 전용 보안 저장소(userdata)나 .env 파일처럼 노트북 코드 안에서 완결되는 방법을 쓴다.
3. (문제 3 풀이) 즉시 오픈AI 대시보드에서 그 키를 폐기(삭제)하고 새 키를 발급받아야 한다. 유출된 키로 발생한 비용은 계정 소유자가 부담하므로, 대시보드의 사용량(Usage)도 함께 확인해 예상 밖의 호출이 있었는지 점검한다. 이후 이미 커밋된 깃 이력에서도 키 값을 제거해야 한다.
4. (문제 4 풀이) 월간 한도(Set a monthly budget)는 그 금액을 넘으면 API 요청 자체를 거부하는 하드 리밋이다. 이메일 알림 한계점(Set an email notification threshold)은 금액에 도달하면 이메일로 알려 주기만 할 뿐 요청을 막지는 못한다. 초과 자체를 막으려면 한도를 걸어야 하고, 사용량을 미리 주시하려면 알림 한계점을 함께 걸어 둔다.